feat(auth)!: adopt better-auth's account-issuer rollback — drop sys_account.issuer, retire the backfill, lift the family to 1.7.3 - #17454

… family

`json-stdout-purity.e2e.test.ts` discovers its family from the source tree —
every command that calls `bootSchemaStack` and declares a `--json` flag — and
reconciles the discovered set against the hand-listed `FAMILY`, whose values are
the argv that actually drive each member through `describe.each`. #17454 landed
`os migrate account-issuer`, a new `--json` face on that seam, without a `FAMILY`
row, so discovery found 13 members against 12 listed and the reconciliation went
red. It merged green because this file is `*.e2e.test.*` and therefore runs only
under `OS_TEST_TIERS=nightly`, which no pull request exercises.

The row is added with the argv that drives it, not merely listed: the bare form
boots (it takes the `os migrate plan` shape — `deferSchemaDdl` + `readOnlyProbe`
— so a missing sqlite file is opened as an empty in-memory database rather than
created), and the driven run satisfies all three halves of the contract on its
own: one JSON document on stdout, no kernel-logger record or `[StandaloneStack]`
line there, and every boot diagnostic still on stderr.

`CONFIG_MISS_FAMILY` is deliberately unchanged: the pre-boot family is the
commands that refuse at `resolveConfigPath()`, and this one never reaches that
helper — it does not import `utils/config.js`, and the source-read
`discoverConfigMissFamily()` returns the same ten members. The overlap assertion
stays `['migrate meta']`.

Claude-Session: https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c
Co-authored-by: Claude <noreply@anthropic.com>

…nvelope they declare (objectstack-ai#17791)

Refs objectstack-ai#17234

⚠️ Deliberately `Refs`, not a closing keyword. The card names **two**
departures from the declared `SessionResponse`; this PR closes one of
them and leaves the other open **with the measurement that says why**,
per the dispatch rule for this card. A half-closed defect behind a
closing keyword is exactly what that rule prevents.

| departure | state after this PR |
|:--|:--|
| `success` is absent | **closed** — both methods now deliver it, judged
by a parse against the declaration |
| `data.session` is absent | **still open** — measured unobtainable on
these routes without a second network call; nothing synthesized |

## Premise, re-measured against `origin/main` before writing code

All three faces read the same as the dispatch recorded them, on
`15805ea3`:

- `git log --oneline -12 origin/main -- packages/client/src/index.ts` —
tip `7baf04ae` (a docs-only OAuth change). Nothing touches `login` /
`register`.
- Both methods still carried the inline `const data = raw && (raw.data
?? …); const normalized = data ? { ...raw, data } : raw;` and neither
wrote `success`.
- Driven through a real `AuthManager` (better-auth **1.7.3**,
organization plugin) over a real `ObjectQL` on a real
`SqliteWasmDriver`:

```
register -> top-level keys ["token","user","data"]             success === undefined
login    -> top-level keys ["redirect","token","user","data"]  success === undefined
both     -> data keys ["token","user"]
both     -> SessionResponseSchema.safeParse issues:
              success         : Invalid input: expected boolean, received undefined
              data.session    : Invalid input: expected object, received undefined
              data.user.image : Invalid input: expected string, received null
```

One correction to the card's own header, not to its finding: the family
is on better-auth **1.7.3** (lifted by objectstack-ai#17454), not 1.7.2.

## The change

`packages/client/src/index.ts` only.

`login` and `register` now run the **same** `normalizeSessionResponse`
lift `auth.me` / `auth.refreshToken` use, instead of a second inline
copy of it. The helper is extended to carry a body's own top-level
`token` into `data.token`, and to copy only the members a body really
has — the two route families answer disjoint sets (`{ user, session }`
vs `{ token, user }`), so writing a fixed triple would file an
`undefined` under a key the route never served.

Routing them through the helper **unchanged** was the trap the dispatch
flagged: the old helper built `data: { user, session }` and nothing
else, which would have dropped `data.token` and silently stopped
`login`'s auto-set of the client bearer token. That is pinned now (block
④), against the wire bytes of the same call.

⛔ No `packages/spec` edit. `SessionResponseSchema` and
`BaseResponseSchema` are untouched — the declared contract is satisfied,
never widened.

## Driven readings — after

Same instrument, same arrangement.
`packages/client/src/auth-login-register-envelope.test.ts`, 12 cases:

```
register -> success === true    BaseResponseSchema.safeParse -> ok
login    -> success === true    BaseResponseSchema.safeParse -> ok
both     -> SessionResponseSchema.safeParse issue paths === ["data.session","data.user.image"]
```

The `success` issue is gone from both. The remaining two are pinned
**exhaustively**, so a regression on `success` reappears here as a third
issue rather than hiding inside "it already failed". `data.user.image`
is objectstack-ai#17235 and is not specific to these methods.

**Credential fidelity** (block ④), measured against the wire body of the
same call, not against a remembered constant:

```
login  -> res.data.token === wireBody.token        (byte-identical)
       -> client.token   === wireBody.token        (auto-set still fires)
       -> principalFor(client.token) === res.data.user.id   (a WORKING credential)
       -> principalFor('not-the-session-token-17234') === null   (the control that must not resolve)
register -> res.data.token === wireBody.token, client.token === wireBody.token
```

**Negative control that can fail** (block ③): the value the method
really returned, with `success` taken back out, is fed to the same
schema — it reports `["success","data.session","data.user.image"]`
again. So a green reading above is a reading, not a broken assertion.

## Why `data.session` is not delivered

Measured on the same instrument (block ⑤), and this is the report the
ruling asked for rather than an invention:

```
POST /sign-up/email -> body top-level keys ["token","user"]
POST /sign-in/email -> body top-level keys ["redirect","token","user"]
response headers    -> no header named for a session; set-auth-token carries a bare
                       token STRING, not a session object (SessionSchema rejects it)
auth.me()  (a SECOND call to GET /get-session) -> data.session parses as SessionSchema
```

`SessionSchema` requires `id`, `expiresAt` and `userId`. `userId` is
derivable from `user.id`; **`id` and `expiresAt` are nowhere on these
two calls, body or header.** So delivering `data.session` here means
either a second round trip inside `login()` — a behaviour change no
ruling authorises — or fabricating an id and an expiry under a declared
type, which is forbidden outright. The card stays open for that shape
decision.

Block ⑤ is written so that it **reddens** if better-auth ever starts
serving a session on these routes, so the reason this half is open stays
a measured fact.

## Reverse verification

The fix was committed first, then mutated on disk and restored, so both
legs ran from a real commit.

```
mutation : drop `success: true` from the lift's return
on-disk  : anchor count 1 -> 0, replacement count 0 -> 1
           blob a4d0655… -> a4ac6283…   (proved changed, not an exit-0 no-op edit)
result   : Tests 6 failed | 12 passed (18)   — VERDICT command-exit 1
           4 of the 6 are this PR's blocks ①/②; the other 2 are objectstack-ai#16760's own
           `auth-get-session-envelope.test.ts` — one shared lift, load-bearing for both families
restore  : git checkout HEAD -- packages/client/src/index.ts
           blob back to a4d0655…, `git diff HEAD` empty, `git status --porcelain` empty
re-run   : Tests 518 passed (518), Test Files 43 passed (43)   — VERDICT command-exit 0
```

Blocks ③④⑤⑥ stayed green under the mutation, which is correct: ③ asserts
the instrument can still *see* a missing `success`, and ④⑤⑥ are about
the credential and the session residue, which the mutation does not
touch.

## Local verification

Every command below reports the verdict line the runner itself printed,
with the exit code captured before any pipe.

| command | verdict |
|:--|:--|
| `pnpm --filter "@objectstack/client^..." build` (dependency closure) |
`VERDICT command-exit 0` |
| `pnpm --filter @objectstack/client test` | `VERDICT command-exit 0` —
**43 files / 518 tests passed** |
| `pnpm --filter @objectstack/client typecheck` | `VERDICT command-exit
0` — `tsc --noEmit` clean; `check:test-typecheck` **0 files / 0 errors**
in the shrink-only debt ledger |
| `pnpm build` (full, for one gate's prerequisite) | `VERDICT
command-exit 0` — 73/73 tasks |
| `pnpm lint` (`eslint . --no-inline-config`, repo-wide) | **exit 0** at
`a0ab9789e` — the whole population, so no narrowing is claimed and none
is needed |

**Gate families**, derived from the real change set rather than from a
hand-written list —
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`, then reconciled with `--ran`:

```
60 derived, 60 run, 0 NOT-MEASURED, 0 UNRUN
(a DERIVED zero — all 60 recorded an exit code and none of them is 3)
```

Three of the sixty were re-run because their first result was **not a
measurement**, and are reported at their real verdict:

- `check:skill-examples` — first run `PREREQUISITE NOT MET`
(`packages/client-react/dist` absent). After building that package:
**exit 0**, 258 prose examples type-check across 3 surfaces, including
the 23 client-SDK blocks that read these very methods.
- `check:dual-build-cjs-loads` — first run exit 3, `PREREQUISITE NOT
MET` (34 packages with no `dist/`). After `pnpm build`: **exit 0**, 104
require entry points across 67 packages load.
- `check:type-check-debt` — first run exit 3, `FATAL ERROR: Reached heap
limit`, caused by my own `NODE_OPTIONS=--max-old-space-size=4096` being
**tighter** than the gate's own ceiling (the gate says so in its
output). Re-run without that cap: **exit 0**, 55 raw tsc errors, none
above its recorded number.

⛔ None of those three was reported as a pass on its first result. An
exit 3 here means *nothing was measured*, which is neither green nor
red.

## objectstack-ai#16760's work is not disturbed

`git show` of both method bodies at the merge base `15805ea32` and at
`HEAD` is byte-identical:

- `auth.me` — 7 lines, unchanged.
- `auth.refreshToken` — 14 lines, unchanged.
- `packages/client/src/auth-get-session-envelope.test.ts` — not in `git
diff --name-only`, and green in the run above.

The shared lift *is* changed, deliberately — and the ablation above
shows it is load-bearing for both families, which is the point of there
being one of it.

## Docs

No documentation change is owed, measured rather than assumed. At
`origin/main` `8fa3fe63`:

```
git grep -c 'data\.session' -- content/docs   ->  0 hits   (exit 1)
git grep -c 'data\.user'    -- content/docs   ->  3 hits   (live positive control)
```

The only page that reads fields off these two calls is
`content/docs/permissions/authentication.mdx`, which reads
`result.data.user`, `result.data.token` and `session.data.user` — all
three preserved by this change. No published page tells a reader to
reach for `data.session`, so leaving that half undelivered falsifies no
documentation. ⛔ Nothing under `content/docs/releases/` is touched: that
tree is release-owned.

Clause-②: no

This pulls an implementation back to a contract that is already
declared. No published surface widens, no accepted set widens, and
nothing in `packages/spec` is edited — the triage ruling on this card
says the same in its own words.

## Acceptance notes

Found while measuring, **not** filed and **not** fixed here:

- The `normalizeSessionResponse` docblock stated that the token `login`
puts at `data.token` is the SIGNED `token.signature` form. Measured, it
is the **unsigned** one: the response BODY's `token` and the
`session.token` a following `/get-session` serves are the same string,
while the signed form is what `bearer()` publishes in the
`set-auth-token` **header**. Corrected in this PR — same file, same
docblock, same subject, as the dispatch order directs — and the
corrected reading is now pinned by a case in block ④ so it cannot rot
again. The rule the sentence justified (never synthesize `data.token`
from a session) is unchanged and now rests on the right ground.
- The same docblock said `auth.login` "has carried the same lift … since
long before this card". That was loose — login's inline copy filled
`data` and never `success`, which is this defect. After this PR it is
literally the same lift, and the sentence is rewritten to say so.
- noted, not filed: `login`'s own `if (!res.ok) { … throw … }` block is
unreachable. `ObjectStackClient.fetch` already throws on every non-2xx
before `login` can inspect `res.ok` (observed directly: a
`SELF_REGISTRATION_CLOSED` sign-up threw from `fetch`, never reaching
the caller's branch). Dead code, not a defect — left untouched.
Successor: whoever converges the SDK's two error envelopes (objectstack-ai#3843 is the
line that would reach it).
- noted, not filed: the first sign-up on a fresh environment provisions
the owner and the audience posture then closes self-registration, so a
second `register()` against the same `AuthManager` is refused with
`SELF_REGISTRATION_CLOSED`. Correct behaviour, and a real trap for
anyone writing a driven auth test — recorded in the suite's own
comments. Successor: the next author writing a multi-user driven auth
test in `packages/client`.
- ⛔ objectstack-ai#17238 (the anonymous-caller case) is not addressed here and is out
of scope: different defect, `domain:services` lane, unruled. objectstack-ai#17235
(`data.user.image` served as `null`) is likewise out of scope and stays
pinned as residue.

Authored by an agent session:
https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c


---
_Generated by [Claude Code](https://claude.ai/code)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

…t-purity family (objectstack-ai#17805)

Part of objectstack-ai#17633 — it repairs the one file the 2026-09-12T05:54Z sweep
names, and carries no closing keyword on purpose.
`test-nightly-tiers.yml` states of its green path: "On green this
workflow files nothing, edits nothing and closes nothing", so the card
is closed by a seat reading a later nightly as `success` — a reading no
merge can assert. objectstack-ai#17633 therefore stays open after this lands; the half
left behind is that confirmation.

Clause-②: no

## What was red

`packages/cli/test/json-stdout-purity.e2e.test.ts`, in `describe('the
family this contract has to hold across')`:

```
FAIL  is exactly the set listed here — a new member goes red until it is driven too
AssertionError: expected [ 'meta resync', …(12) ] to deeply equal [ 'meta resync', …(11) ]
+   "migrate account-issuer",
```

That file DISCOVERS its family from the source tree — every command
under `packages/cli/src/commands` that calls `bootSchemaStack(` and
declares `json: Flags.boolean(` — and reconciles the discovered set
against the hand-listed `FAMILY`. `FAMILY` is not a list of names:
`describe.each(Object.keys(FAMILY))` drives every key, and each value is
the extra argv that drives it. So a row is a promise that the member is
actually exercised.

`os migrate account-issuer` landed in `9bd4344e4` (by objectstack-ai#17454) as a new
`--json` face on that seam, without a `FAMILY` row. Discovery found 13
members against 12 listed. It merged green because this file is
`*.e2e.test.*`, which runs only under `OS_TEST_TIERS=nightly` — the
class this card exists to see.

Symbols, not line numbers: `FAMILY` is at `:82`, `discoverFamily()` at
`:129`, the reconciliation at `:209`, `describe.each` at `:248`. All
four are still at the line numbers the card body recorded at 05:54Z, on
the tree this branch was cut from.

## The premise, measured before any edit

The premise to falsify was that `os migrate account-issuer --json`
already SATISFIES the stdout-purity contract and only its `FAMILY` row
is missing. It was driven by hand against the fixture this suite builds,
before the row existed. It holds, on all three halves:

```
$ cd FIXTURE && NO_COLOR=1 OS_DATABASE_URL="file:FIXTURE/migrate-account-issuer.db" \
    tsx packages/cli/bin/run-dev.js migrate account-issuer --json
EXIT=1
stdout (1 line, bare JSON.parse succeeds — keys: error, code):
{"error":"Cannot enumerate sys_account: The database refused to run this query for object 'sys_account'. … Refusing rather than reporting an unread table as clean.","code":"RESOURCE_CONFLICT"}
```

| half of the contract | reading on stdout | reading on stderr |
|:--|:--|:--|
| exactly one JSON document | `JSON.parse` of the whole stream succeeds
| — |
| no kernel-logger record, no `[StandaloneStack]` | 0 matches for each |
— |
| `[StandaloneStack] no compiled artifact` | 0 | 1 |
| `Bootstrap complete` | 0 | 1 |
| `Graceful shutdown complete` | 0 | 1 |

So this is a test-only diff, and the branch the dispatch order reserved
for a purity DEFECT was not taken.

## The fix

One `FAMILY` row, with the argv that drives it — `[]`, the bare form. It
boots because this command takes the `os migrate plan` shape
(`deferSchemaDdl: true` + `readOnlyProbe: true`), so the fixture's
absent sqlite file is opened as an empty in-memory database rather than
brought into existence. No `sys_account` table exists there, so the face
driven is the command's REFUSAL face: the `emitJson(…, 1, { compact:
true })` branch, which is the noisier of its two emit paths — every
driver and kernel diagnostic the failed scan produces is emitted before
it. The clean-report face is unreachable in this fixture by
construction, and the header already states why the fixture stays
uncompiled and minimal.

## `CONFIG_MISS_FAMILY`: decided NO, from the source rather than from
the colour

`migrate account-issuer` does NOT belong to the pre-boot family, and the
overlap assertion stays `['migrate meta']`.

`discoverConfigMissFamily()` takes a command iff it declares `json:
Flags.boolean(` AND imports from `utils/config.js` — directly, or
through a class it extends. `account-issuer.ts` imports
`utils/format.js` and `utils/schema-migrate.js` and extends `Command`;
it never reaches `resolveConfigPath()`, so it has no refusal branch for
that family to drive. Re-running the shipped discovery over this tree
returns the same ten members, `migrate account-issuer` not among them,
and `preBoot` is still length 10.

This is the decision, not its consequence: had it been hand-added to
`CONFIG_MISS_FAMILY`, the `:227` reconciliation would have gone red
precisely because the discovery disagrees — the pin catches a
hand-addition, which is the same evidence read from the other side.

## Verification

All runs in one worktree, through `scripts/pm/os-verify-lock.sh`; the
verdict line quoted is the one the wrapper prints.

1. RED reproduced first, on the tier that shows it, at `8da783206`
before the edit:

```
$ OS_TEST_TIERS=nightly pnpm --filter @objectstack/cli exec vitest run \
    --project integration test/json-stdout-purity.e2e.test.ts
 ❯ test/json-stdout-purity.e2e.test.ts (38 tests | 1 failed) 89131ms
 × is exactly the set listed here — a new member goes red until it is driven too
AssertionError: expected [ 'meta resync', …(12) ] to deeply equal [ 'meta resync', …(11) ]
+   "migrate account-issuer",
 ❯ test/json-stdout-purity.e2e.test.ts:209:30
 Test Files  1 failed (1) · Tests  1 failed | 37 passed (38)
os-verify-lock: VERDICT command-exit 1
```

Byte-for-byte the failure the card records, down to the diff line and
`:209:30`.

2. GREEN after, same command, with the member DRIVEN — three new
per-member cases appear, 38 tests become 41:

```
 ✓ os migrate account-issuer --json > emits ONE JSON document on stdout — a bare JSON.parse, no extraction
 ✓ os migrate account-issuer --json > leaves no kernel-logger record on stdout
 ✓ os migrate account-issuer --json > still shows the operator every boot diagnostic — on stderr
 Test Files  1 passed (1) · Tests  41 passed (41) · Duration 97.75s
os-verify-lock: VERDICT command-exit 0
```

3. A control that can fail — two legs, each mutating this file on disk,
each proving the mutation landed by hash and restoring under a `trap …
EXIT INT TERM` that re-checks the hash against the HEAD blob
(`d30b0f4d06e56ca0ed0243207f7d2e42d6f52031`). No `dist` is involved:
vitest loads this test file from source, so there is no built artifact
for the mutation to fail to reach.

LEG A — the positive control, the driven run's own output and exit code.
A temporary case read the captured run for `migrate account-issuer` and
asserted its payload and its exit status, then was removed:

```
ABLATION-A stdout: {"error":"Cannot enumerate sys_account: … Refusing rather than reporting an unread table as clean.","code":"RESOURCE_CONFLICT"}
ABLATION-A exit code: 1
 ✓ ABLATION-A temporary control > the account-issuer ROW really drove the command: its output and exit code
 Tests  42 passed (42)
```

That payload belongs to no other member of the family — it is this
command's own `sys_account` refusal — so the row is driving the command
it names, not merely sitting in a list.

LEG B — the mutation, a row that drives NOTHING. The row's argv became
`['--drives-nothing']`, which oclif refuses above the command:

```
 × os migrate account-issuer --json > emits ONE JSON document on stdout — a bare JSON.parse, no extraction
 × os migrate account-issuer --json > still shows the operator every boot diagnostic — on stderr
AssertionError: expected 'objectstack: INVOCATION ERROR — Nonex…' to contain '[StandaloneStack] no compiled artifact'
+ objectstack: INVOCATION ERROR — Nonexistent flag: --drives-nothing. The command never ran: nothing was started and nothing is listening.
 Tests  2 failed | 39 passed (41)
```

So a row that drives nothing cannot pass as one that does. Reported as
measured, including the part that is not flattering: the THIRD case,
`leaves no kernel-logger record on stdout`, stayed GREEN through leg B.
It is a pair of negative assertions, and they are vacuously true of an
empty stdout — it binds purity, not existence. The two that do bind
existence are enough for this row, and the trio is unchanged by this PR.

Restore was verified on both legs by hash equality with the HEAD blob
and an empty `git diff HEAD`, not by an exit code.

4. Gate families, derived from the change set rather than listed by hand
— `node scripts/pm/dispatch-gates.mjs --commands` with no paths, then
reconciled with `--ran` carrying each recorded exit code:

```
Run reconciliation — 48 derived, 47 run, 1 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 48 derived famil(ies) accounted for — 47 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3).
```

The one NOT MEASURED is `pnpm check:dual-build-cjs-loads`, and it is not
a red: it exits 3 with `PREREQUISITE NOT MET — this gate reads built
output, and some package has no dist/ … ⛔ This is NOT a pass: nothing
was measured`, naming twelve packages outside this card's build closure.
It needs a whole-repo `pnpm build`; CI builds everything and is the
authority on it. `pnpm check:nul-bytes` is in the 47 and green; a
control-character sweep over the edited file (`grep -naP` over the C0
set plus DEL) also returns nothing.

5. `pnpm --filter @objectstack/cli build && pnpm --filter
@objectstack/cli typecheck` — `VERDICT command-exit 0`. Reported
precisely, because the two halves do not cover the same files:
`tsconfig.json` declares `include: ["src"]`, so the `tsc --noEmit` half
does NOT reach `test/`; the half that reaches this diff is
`check:test-typecheck`, which reports `@objectstack/cli's test layer
compiles under packages/cli/tsconfig.test.json`.

6. The pin re-checked against the CURRENT `main`, not only against the
base this branch was cut from. `origin/main` at `310760d22` touches
neither `packages/cli/src/commands` nor `packages/cli/test` since
`8da783206`, and running the shipped discovery over `origin/main`'s own
tree returns exactly the thirteen members `FAMILY` carries after this
PR. So the set is right against the tree this will land on.

7. `node scripts/pm/check-clause2-carriers.mjs --pair 17805` — exit 0:
"the clause-② declaration is readable in the fixed spelling and both
carriers agree, and its diff carries no widening tell."

Not run locally and left to CI, declared rather than implied:
`packages/cli`'s `integration` tier beyond this one file, the repo-wide
`pnpm lint`, and the whole-repo build `check:dual-build-cjs-loads`
needs.

Session: https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c

## Changeset

**None, deliberately.** Measured rather than assumed: `@objectstack/cli`
declares `files: ["dist", "README.md", "CHANGELOG.md"]`, and after `pnpm
--filter @objectstack/cli build`, a string unique to this diff (`the
noisier of its two`) has **0** hits across all three of those paths,
while the positive control on the same pass — `Pre-flight the retirement
of sys_account.issuer`, the command description that really does ship —
has **1**, in `packages/cli/dist/commands/migrate/account-issuer.js`.
The matcher fires, so the zero is a reading. `packages/cli/test/**` is
not under any published path and `dist/` carries no compiled test file.
Nothing published moves, so this is the `skip-changeset` case rather
than a missing one.

## Acceptance notes

- Measured and left alone: `leaves no kernel-logger record on stdout` is
vacuously green against a run that never happened (leg B above). It is
correct for what it asserts — purity, not existence — and the sibling
cases in the same trio cover existence. Noted, not filed: it is a
property of the whole `describe.each` block, no in-flight PR holds this
file, and changing it is a pin redesign rather than this card.
- Reading, no claim attached: the driven refusal payload carries
`"code":"RESOURCE_CONFLICT"` for a missing `sys_account` table, via
`errorCodeFields()` over the sql driver's deliberately unattributable
`DATABASE_ERROR`. Recorded because it is what the driven run prints; no
contract text and no repro of harm was gathered, so nothing is filed and
no follow-up owner is claimed.
- `CONFIG_MISS_FAMILY` and the `:227`/`:236` overlap assertion were
examined and deliberately left unchanged — the reasoning is in its own
section above, from the command's imports and the shipped discovery, not
from which answer happened to be green.

---
_Generated by [Claude Code](https://claude.ai/code)_

Co-authored-by: Claude <noreply@anthropic.com>

…rocess, and the canonical origin follows the listener (objectstack-ai#17725)

Fixes objectstack-ai#16804

**objectstack dev** `--cert` <path> `--key` <path>
terminates TLS in the dev process itself, and every origin the boot
advertises follows the listener. This is director-seat ruling
[`5617187807`](objectstack-ai#16804 (comment)),
batch objectstack-ai#111 item 1, option **N (narrow)** — parts (1)+(2) of the card's
Ask in exactly that shape.

## ⛔ No CA generation, and no trust-store prose — 不生成 CA、不写信任库指引

The ruling, quoted verbatim (⛔ not paraphrased — 引用中文裁决时保持原文):

> **裁定**：objectstack dev --cert <path> --key
<path>：开发者自带证书，dev 进程内终止 TLS；同笔做 (2)：规范 origin 自动为
`https://localhost:<port>`，两个 `.well-known/*` 文档随之广播 https，`OS_AUTH_URL`
只作覆盖（`resolveAuthBaseUrl` 的硬编码 `http://` 回落尾巴按 listener 协议派生）。⛔ 不生成自签
CA；⛔ 不打印、不文档化任何「把 CA 装进系统信任库」的指引——信任库是开发者自己的事。

So, in as many words: **this PR generates no certificate and no CA, and
it writes no instruction anywhere — not in code, not in `--help`, not in
a doc page, and not as a suggestion in this body — for installing a
certificate into a system trust store.** The trust store is the
developer's own business. The developer brings the certificate; the
feature's whole job is to *use* it. Option **F** (generated CA + trust
instructions) is refused on the ruling's security-statement ground;
option **X** (document the proxy recipe) is not delivered.

That refusal is **asserted, not merely promised**:
`dev-tls-contract.test.ts`'s last `describe` reads both flag
descriptions and the module's own source for `trust store` / `keychain`
/ `certutil` / `add-trusted-cert` / `self-signed` / `generated CA` and
for `node:crypto`, `generateKeyPairSync`, `X509Certificate`, and an
ANTI-VACUITY case proves the same scan finds words that *are* there — so
a future edit adding that prose cannot pass by having nothing to read.

## The confidence gap the ruling handed the implementing seat — MEASURED

> 置信缺口留给实施席先测：Hono 适配层接 Node TLS 的成本（`packages/cli/src` 今天零处 TLS 代码），超出
M 级停手回报。

**Reading: XS.** `@hono/node-server@2.1.1` takes the listener factory as
an *option*. Its exported `Options` type is a union whose https arm is,
verbatim from `node_modules/@hono/node-server/dist/index.d.mts`:

```ts
type createHttpsOptions = {
  serverOptions?: ServerOptions$2;              // node:https ServerOptions
  createServer?: typeof createServer$2;         // node:https createServer
};
```

So terminating TLS needs **no bridging code at all** — the same `fetch`
handler, the same route table, the same graceful drain, one different
server factory. Well under an M; no stop was warranted.

## Premise check — all four re-derived on this branch's base `6fa2a8ae`,
all four hold

| # | premise | re-derived here |
|:--|:--|:--|
| 1 | `resolveAuthBaseUrl` has a hardcoded `http://` fallback tail | ✓
`packages/cli/src/commands/serve.ts:5634` declared it; `:5637` was ``??
`http://localhost:${port}` `` |
| 2 | `packages/cli/src` contains **zero** TLS code | ✓
`https.createServer` · `createSecureServer` · `node:tls` · `node:https`
→ **0** each. Positive control from the same tree: `createServer` → 3
hits (`commands/serve.ts:255` — a `net.createServer()` port probe — plus
`utils/port-contract.ts:52` and `serve-port-validation.test.ts:96`, both
in prose), `from 'node:` → 313 |
| 3 | `dev` declares no `--cert` / `--key` | ✓ zero on `dev.ts` +
`serve.ts`; `dev`'s flags are at `commands/dev.ts:128` (`static override
flags`). The only `cert`-shaped hits in `serve.ts` were the word
"certainly" at `:410` and `/.well-known/*` prose at `:5036` |
| 4 | part (3) is already fixed by objectstack-ai#16734 / PR objectstack-ai#16812 | ✓
`printMcpConnectHint` already resolves through `resolveAuthBaseUrl`;
**not** re-implemented here |

`packages/plugins/plugin-hono-server/src/adapter.ts` likewise had
**zero** `https` hits, against a same-file positive control of 8 for
`key` — so the TLS arm is genuinely new rather than a second copy of
one.

## What follows the listener, and what deliberately does not

`resolveAuthBaseUrl(port, boundProtocol)` — **only the built-in default
tail moves.** That tail is the one link in the chain nobody configured:
it is the process describing its own socket, and once TLS terminates
in-process http://localhost:&lt;port&gt; is an address no client can
reach.

⛔ Every **configured** link keeps winning — `OS_AUTH_URL`, the legacy
`BETTER_AUTH_URL`, `OS_BASE_URL` — **an `http://` value included.** They
answer a different question: where the deployment is *reached*, which
behind a proxy or a tunnel has no relation to what this process bound. A
default has no standing to overrule an operator's deliberate statement
about a different hop, and a "helpful" scheme upgrade there would be a
bug wearing a feature's clothes.

Because the whole boot already routed through that one resolver, the
three acceptance surfaces follow with no second reader: the two
`/.well-known/*` documents (`AuthManager.getCanonicalOrigin()` ←
`AuthPlugin({ baseUrl })` ← `resolveAuthBaseUrl`), the CSRF allow-list,
the ready banner's `API:` / `MCP:` rows, and the `🤖 MCP server` block.

`publishBoundPort(..., boundProtocol)` is the **socket's own** address
rather than the canonical origin, so it is ⛔ *not*
`OS_AUTH_URL`-overridable: both of its consumers *open* that url — the
runtime state file is what an external supervisor dials, the IPC message
is what the `os dev` parent learns the server from — and a hardcoded
`http://` under a TLS listener hands both a machine-readable address
that answers a handshake error. This change is what makes that surface
false, so it ships with it.

## Acceptance — driven on a real boot of `examples/app-todo`, bytes
pasted

### ① `--cert`/`--key`, `OS_AUTH_URL` unset — all three surfaces give
https

`node packages/cli/bin/run.js dev --fresh -p 38471 --cert CERTPATH --key
KEYPATH`
(CERTPATH / KEYPATH are the two real file paths; spelled as words
because a
bracketed placeholder does not survive a GitHub body write):

```text
  ➜  API:       https://localhost:38471/
  ➜  MCP:       https://localhost:38471/api/v1/mcp
      connect an AI client (Claude Code, Cursor, …) · skill: https://localhost:38471/api/v1/mcp/skill

  🤖 MCP server — connect a coding agent:
     Endpoint  https://localhost:38471/api/v1/mcp
     Skill     https://localhost:38471/api/v1/mcp/skill
     Connect   claude mcp add --transport http app-todo https://localhost:38471/api/v1/mcp
     Disable   OS_MCP_SERVER_ENABLED=false
```

`GET /.well-known/oauth-protected-resource` over that real TLS socket:

```json
{
  "resource": "https://localhost:38471/api/v1/mcp",
  "authorization_servers": ["https://localhost:38471/api/v1/auth"],
  "scopes_supported": ["data:read", "data:write", "actions:execute", "offline_access"],
  "bearer_methods_supported": ["header"],
  "resource_name": "ObjectStack MCP"
}
```

`GET /.well-known/oauth-authorization-server` (url-valued fields):

```json
{
  "issuer": "https://localhost:38471/api/v1/auth",
  "authorization_endpoint": "https://localhost:38471/api/v1/auth/oauth2/authorize",
  "token_endpoint": "https://localhost:38471/api/v1/auth/oauth2/token",
  "jwks_uri": "https://localhost:38471/api/v1/auth/jwks",
  "registration_endpoint": "https://localhost:38471/api/v1/auth/oauth2/register"
}
```

And the listener really is TLS — plain http on that same port, with its
exit code captured **before** any pipe:

```text
$ curl -sS --noproxy '*' -m 10 http://localhost:38471/.well-known/oauth-protected-resource > log 2>&1; echo "EXIT=$?"
EXIT=52
curl: (52) Empty reply from server
```

The runtime state file names the socket, not a guess:
`{"pid":27532,"port":38471,"url":"https://localhost:38471",...}`.

### ② Without the flags — identical to today

Same command, flags removed, port 38472:

```text
  🤖 MCP server — connect a coding agent:
     Endpoint  http://localhost:38472/api/v1/mcp
     Skill     http://localhost:38472/api/v1/mcp/skill
     Connect   claude mcp add --transport http app-todo http://localhost:38472/api/v1/mcp
  ➜  API:       http://localhost:38472/
  ➜  MCP:       http://localhost:38472/api/v1/mcp
```
```json
{ "resource": "http://localhost:38472/api/v1/mcp",
  "authorization_servers": ["http://localhost:38472/api/v1/auth"] }
```
state file: `{"port":38472,"url":"http://localhost:38472",...}`

⭐ **Pinned as an ablation, not a claim** — three legs, each requiring
the omitted argument and an explicit `http` to be *identical* while both
differ from `https`:

- `dev-mcp-connect-hint-origin.test.ts` — `bootWithoutProtocolArg()`
reproduces this file's pre-change call expression character for
character and drives it beside today's call; the whole captured boot
buffer (banner + hint, `console.error` and `console.log` in call order)
must match byte for byte, over a plain port, dev's auto-shifted port and
an ephemeral one.
- `serve-auth-base-url-diagnostic.test.ts` — `resolveAuthBaseUrl(port)`
must equal `resolveAuthBaseUrl(port, 'http')` and differ from
`resolveAuthBaseUrl(port, 'https')`.
- `serve-bound-port-publication.test.ts` — the same, for the state-file
payload and the IPC message.
- `adapter-tls-listener.test.ts` — the http and https listeners are
constructed identically but for the fourth argument, and each
**refuses** the other's protocol, so neither leg can pass by being
broken in a convenient direction.

### ③ `OS_AUTH_URL` still wins

`OS_AUTH_URL=https://tunnel.example.com` **with** both TLS flags, port
38473:

```text
  ➜  API:       https://tunnel.example.com/
  ➜  MCP:       https://tunnel.example.com/api/v1/mcp
     Endpoint  https://tunnel.example.com/api/v1/mcp
     Connect   claude mcp add --transport http app-todo https://tunnel.example.com/api/v1/mcp
```
```json
{ "resource": "https://tunnel.example.com/api/v1/mcp",
  "authorization_servers": ["https://tunnel.example.com/api/v1/auth"] }
```

…while the state file still names the socket:
`{"port":38473,"url":"https://localhost:38473",...}` — the canonical
origin and the bound address answering their own questions, as designed.
The awkward direction is pinned too: an `http://` `OS_AUTH_URL` under a
TLS listener is **not** upgraded.

### Refusals — loud, and never degraded to plain http

```text
$ os dev --cert CERTPATH                                  # EXIT=1
  ✗ --cert was given without --key.
    TLS needs both halves: --cert CERT-PATH-PLACEHOLDER --key KEY-PATH-PLACEHOLDER.
    Drop both to serve plain http on this port.

$ os dev --cert /no/such/cert.pem --key /no/such/key.pem  # EXIT=1
  ✗ --cert could not be read: "/no/such/cert.pem"
    ENOENT: no such file or directory, open '/no/such/cert.pem'
    The path is resolved relative to the current working directory.
```

⚠️ In the first block the notice's two bracketed placeholders are
rendered here as
CERT-PATH-PLACEHOLDER / KEY-PATH-PLACEHOLDER. The bytes the CLI actually
prints are
angle-bracketed (`path to the certificate` and `path to its private key`
inside angle
brackets) and are pinned verbatim in `dev-tls-contract.test.ts`; a
bracketed span does
not survive a GitHub body write, so it is spelled out rather than
silently eaten.

⛔ There is deliberately no path from either refusal back to an http
listener: a developer who typed `--cert` asked for TLS, and answering
with the other protocol would surface first as a client-side handshake
error naming neither the flag nor the file. Prefer failing to falling
back.

## Shape of the change

`packages/cli/src/utils/dev-tls-contract.ts` is the **one** reader of
the pair, shared by `dev` and the `serve` child it spawns — the same
judgement as `port-contract.ts`, for the same reason: before it, a value
typed at `dev` would have been refused one process later under the name
of the channel it arrived on. `dev` forwards the **paths**, never the
bytes, so exactly one process reads the file and exactly one owns that
refusal — and the parent's `boundProtocol` comes from the same
`resolveDevTlsIntent` call that built the child's argv, so the scheme
the hint prints and the scheme the child binds cannot part company
(pinned: exactly one `resolveDevTlsIntent(` call in `dev.ts`).

`HonoPluginOptions.tls` takes PEM **bytes**, ⛔ not paths: whoever hands
the adapter TLS material is the layer that knows why it has it and can
name the flag the operator typed. A transport adapter taking paths would
own a second reader of the same file and would have to invent a refusal
from a filename.

## Scope — declared growth, and two fences confirmed clear

The dispatch's declared face was `commands/dev.ts`, `commands/serve.ts`
and their tests. The delivered diff **grew** into
`packages/plugins/plugin-hono-server` (`adapter.ts`, `hono-plugin.ts`,
one new test) and `packages/cli/src/utils`, because `serve()` — the only
place a listener is created — lives in the adapter, and putting TLS
anywhere else would have meant a second listener owner (Route & surface
ownership §1). Contract-first: the option belongs at the producer.

Checked rather than assumed: **no open PR holds any file in this diff.**
All 9 open PRs' file lists were read; PR objectstack-ai#17454's cli files are
`index.ts`, `commands/init.ts`,
`commands/migrate/{account-issuer,apply}.ts` — disjoint from every path
here — and no open PR touches `plugin-hono-server` at all. ⛔ No
`packages/spec` edit: `HonoPluginOptions` is declared locally in
`hono-plugin.ts`, so the new option needed none (`packages/spec` was
read only). ⛔ `content/docs/releases/` untouched.

`Clause-②` re-derived from the **delivered** diff: still **yes** — two
new public CLI flags on two commands, a new exported module, a widened
exported `resolveAuthBaseUrl` / `publishBoundPort` signature (both
additive defaults), and a new public `HonoPluginOptions.tls`.

## Two pins this change moved, and why they are updated rather than
deleted

`serve-bound-port-publication.test.ts` held three source-text pins that
went red on the first run — exactly their job. Each is updated to the
new spelling with its intent intact: the banner pin still asserts the
origin comes from `boundPort` (not `port`), the publish-site pin still
asserts the seam is handed the resolved bound port, and the positive
control for the `not.toContain` negatives still asserts `port` reaches
the transport under its own name — now by reading the construction site
rather than one formatting of it.

## The acceptance-2 pins CAN fail — proven by mutation, not by
inspection

An ablation leg only means something if it goes red when the thing it
guards moves. Driven
from the committed state, on disk, with the restore in a `trap`:

**Mutation.** Both `boundProtocol: ListenerProtocol = 'http'` defaults —
`resolveAuthBaseUrl`'s
and `publishBoundPort`'s; there are exactly two, and the script refuses
to proceed on any
other count — flipped to `'https'`, which is precisely the "derived
protocol leaked into the
default" regression.

```text
HEAD blob: 8afd9f4
before: old-spelling=2  new-spelling=0
after:  old-spelling=0  new-spelling=2      <- the edit REACHED THE DISK
mutated blob: 2ae1e42c1400fcb736763b5e18243554198f685a

MUTATED_EXIT=1      Test Files  2 failed (2)      Tests  5 failed | 48 passed (53)

restored blob: 8afd9f4   <- byte-identical to HEAD
git diff HEAD: empty;  git status --porcelain: []

RESTORED_EXIT=0     Test Files  2 passed (2)      Tests  53 passed (53)
```

⚠️ Observed direction: **turns red** — the ordinary one. The five that
failed:

```text
× resolveAuthBaseUrl — precedence (pre-existing behaviour, unchanged)
    > falls back to http://localhost:<port> when no variable is set
× resolveAuthBaseUrl — the listener protocol reaches the TAIL and stops there
    > ABLATION: the omitted argument and an explicit `http` are the same call
× without the flags the output is byte-for-byte what it was
    > the no-flag boot equals the boot that never passes a protocol at all
    > the two legs also agree on an auto-shifted port and an ephemeral one
    > and the legs DISCRIMINATE — the https leg differs from both
```

⭐ The first of those five is **not one of this PR's tests** — it is the
pre-existing objectstack-ai#10202
pin, which has guarded that fallback since before `--cert` existed. A
mutation that reddens a
pin written years before the feature is the cleanest available evidence
that acceptance 2 is
guarded by the tree and not merely by this PR's own assertions.

Discipline notes, since each is a way this measurement could have been
void: the restore is
`git checkout HEAD -- <absolute path>` (⛔ never bare `git checkout --`,
which restores the
mutation back out of the index); it is verified by `git diff HEAD` being
empty and by blob
equality, ⛔ never by an exit code; the `trap … EXIT INT TERM` uses an
absolute path resolved
from `git rev-parse --show-toplevel`; and an empty or unresolvable blob
hash is treated as a
FAILURE rather than as "nothing to compare". No mutated file survives —
the final tree is
clean at `03ba3112`.

## Gates — every derived family measured, at `03ba3112`

The set was **derived from the delivered diff**, not taken from the
dispatch's list:
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`, re-derived
after the docs commit (13 paths → **95** commands, 30 of them families
only the two
`content/docs/` paths schedule). Reconciled back:

```text
Run reconciliation — 95 derived, 95 run, 0 NOT-MEASURED, 0 UNRUN.
```

**95 / 95 green.** Four needed a second pass, and each one is worth
naming:

| family | first pass | why, and what closed it |
|:--|:--|:--|
| `check:nul-bytes` | **exit 1 — a real finding** | A scripted edit had
materialised `\u001b` into a raw `0x1b` byte in
`dev-tls-contract.test.ts:209`, in the very assertion that is *about*
that byte — the exact slip the gate's header says every occurrence in
this repo came from. Fixed to the escape text in `c6500241`; now `OK
(scanned 8438 text file(s) … no raw ASCII control bytes)`, plus a `grep
-naP` self-scan over every changed file returning empty |
| `check:dual-build-cjs-loads` | exit 3 | `PREREQUISITE NOT MET` —
unbuilt sibling packages, ⛔ not a pass and ⛔ not a red. Re-run after the
closure builds: `✓ 104 published require entry point(s) across 67
package(s) load; 620 emitted CommonJS file(s) parse` |
| `check:i18n-coverage` | exit 3 | Same class — `os lint` could not load
`app-showcase`'s config against an unbuilt `connector-mcp`, so *nothing
was compared*. Re-run: `OK (13 config(s), 621 baselined untranslated
string(s), none new)` |
| `check:type-check-debt` | exit 3 | The `--re-measure` leg OOM'd —
under **my own** `NODE_OPTIONS=--max-old-space-size=4096`, which is
*below* the 6144 MB CI-shaped ceiling the gate pins for itself. It
refused to record 0 rather than lying. Re-run at 8192: `OK — 5 ledger
entr(ies) re-measured in 98.2s, 55 raw tsc error(s) total, none above
its recorded number` |

⚠️ An `exit 3` from any of those three is `PREREQUISITE NOT MET` — **NOT
MEASURED**, in neither direction — so none of them was reported green
until it had actually run.

**`pnpm lint` — the full union, not a narrowing.** The lane adds it and
`dispatch-gates.mjs` does not name it. It completed over the whole repo
at the final commit `03ba3112` (clean tree, `git status --porcelain`
empty):

```text
node --stack-size=4000 node_modules/eslint/bin/eslint.js . --no-inline-config --format json
→ 6638 files linted · 0 errors · 0 warnings   (exit 0)
```

The 10 changed `.ts` files also lint clean on their own (`--format json`
→ 10 files, 0/0). Since the union ran, no invariance argument is owed;
for the record, this repo's single `eslint.config.mjs` enables **no**
type-aware linting (zero `parserOptions.project` / `projectService`
matches — the config says so itself at `:328`), so a diff here cannot
move an untouched file's verdict anyway.

**Build / typecheck / tests**, all through
`scripts/pm/os-verify-lock.sh` (one lock per container):

| run | verdict |
|:--|:--|
| `pnpm --filter '@objectstack/plugin-hono-server^...' --filter
'@objectstack/cli^...' build` | `VERDICT command-exit 0` (held 453s) |
| the two packages' own `build` + `typecheck` | `VERDICT command-exit 0`
|
| `plugin-hono-server` — `adapter-tls-listener` + `adapter-drain` | `2
passed` files, **8 passed** tests |
| `cli --project unit` — the four pin files | `4 passed` files, **102
passed** tests |

`packages/cli`'s `integration` tier is **declared to CI**: no path in
this diff is an integration-tier file, a `bin/` entry or
`test/helpers/serve-process.ts`, so `--project unit` is what is owed
locally.

## Acceptance notes

- `check:nul-bytes` caught a real defect in this PR before it was
pushed: a Python-driven edit materialised `�` into a raw `0x1b` byte in
`dev-tls-contract.test.ts`. Fixed to the escape text; gate re-run green
over 8438 files, plus a `grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]'`
self-scan over every changed file returning empty.
- **noted, not filed** — `publishBoundPort`'s url is
`localhost`-hardcoded on the host half as well as the scheme half. Under
a non-loopback bind that host is already wrong today, independently of
TLS; this change touches only the scheme, and the host is out of this
card's scope. Carrier: whoever next changes the bind host — no PR or
card currently in flight names it.
- **noted, not filed** — `AuthManager.getCanonicalOrigin()`'s own
fallback is `'http://localhost:3000'` (`auth-manager.ts:6088`), reached
only when no `baseUrl` is configured at all. Every `os serve` / `os dev`
path passes one, so this branch is unreachable from the CLI and no TLS
boot can hit it. Not a defect from any door this card opens. Carrier:
whoever composes an `AuthPlugin` without a `baseUrl`.

---

## 维护者速读（草稿）

**改了什么。** `objectstack dev --cert <证书> --key <私钥>` 两个新 flag：开发者自带证书，dev
进程自己终止 TLS。给了这两个 flag 之后，这次启动对外宣告的所有地址一律变成 `https://localhost:<端口>`——两个
`/.well-known/*` 发现文档、CSRF 白名单、就绪横幅的 `API:`/`MCP:` 行、`🤖 MCP server`
连接提示，以及外部监管进程会去拨的 runtime 状态文件。不给 flag 时逐字节和今天一样。

**为什么改。** 桌面端 MCP 客户端拒绝对非 https 地址发起 OAuth
登录，所以产品页面承诺的「交互式客户端自动弹浏览器登录」在本地开发服务器上根本演示不了。以前唯一的走法是镜头外手搭一页 openssl +
反向代理再手设 `OS_AUTH_URL`——每次演示、每次录屏、每次排查都要重来一遍。这一笔把那页准备工作删掉。

**风险与代价（含回滚）。** ⛔ 不生成任何证书或 CA，⛔ 也不在任何地方（代码、`--help`、文档、本 PR 正文）写「把 CA
装进系统信任库」的指引——信任库仍然是开发者自己的事，这条由测试反向断言把守，将来有人加这句话会红。dev 进程在给了 flag
时持有一份私钥，这是自带证书方案本来就有的性质，不新增。风险面很窄：不给 flag 时代码路径与今天完全相同，已由四处消融测试钉住。回滚 =
revert 本 PR，无数据迁移、无配置残留、无已发布键退役。已配置的 `OS_AUTH_URL` 一律优先（连 `http://`
的值也不被「升级」），所以任何现有部署的行为不动。

**席位意见。** _（留空，待维护者定稿）_

**你要做的。** 这是新公开 CLI 面（`Clause-②: yes`），已挂
`needs:contract-review`。请确认两点：① 两个 flag 的名字与描述文案；② 「只有回落尾巴跟随
listener、所有已配置值一律优先」这条边界是你要的。确认后按常规合并即可。

This pull request was authored by Claude Code in session
`session_01TSf4DV7ziu4V5j73e46b7c`; that sentence is the durable
attribution, kept
in prose because a PR body's footer block is not reliably preserved by
the platform.


---
_Generated by [Claude Code](https://claude.ai/code)_

---------

Co-authored-by: Claude <noreply@anthropic.com>